home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / string.z / string
Encoding:
Text File  |  2002-10-03  |  18.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ssssttttrrrriiiinnnngggg((((3333CCCC))))                                                          ssssttttrrrriiiinnnngggg((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _ssss_tttt_rrrr_iiii_nnnn_gggg: _ssss_tttt_rrrr_cccc_aaaa_tttt, _ssss_tttt_rrrr_dddd_uuuu_pppp, _ssss_tttt_rrrr_nnnn_cccc_aaaa_tttt, _ssss_tttt_rrrr_cccc_mmmm_pppp, _ssss_tttt_rrrr_nnnn_cccc_mmmm_pppp, _ssss_tttt_rrrr_cccc_pppp_yyyy, _ssss_tttt_rrrr_nnnn_cccc_pppp_yyyy,
  10.      _ssss_tttt_rrrr_llll_eeee_nnnn, _ssss_tttt_rrrr_cccc_hhhh_rrrr, _ssss_tttt_rrrr_rrrr_cccc_hhhh_rrrr, _ssss_tttt_rrrr_pppp_bbbb_rrrr_kkkk, _ssss_tttt_rrrr_ssss_pppp_nnnn, _ssss_tttt_rrrr_cccc_ssss_pppp_nnnn, _ssss_tttt_rrrr_tttt_oooo_kkkk, _ssss_tttt_rrrr_ssss_tttt_rrrr
  11.      _ssss_tttt_rrrr_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp, _ssss_tttt_rrrr_nnnn_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp, _iiii_nnnn_dddd_eeee_xxxx, _rrrr_iiii_nnnn_dddd_eeee_xxxx, _ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr - string operations
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_rrrr_iiii_nnnn_gggg_...._hhhh_>>>>
  15.  
  16.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_cccc_aaaa_tttt _((((_cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  17.  
  18.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_dddd_uuuu_pppp _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_))))_;;;;
  19.  
  20.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_nnnn_cccc_aaaa_tttt _((((_cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_,,,, _ssss_iiii_zzzz_eeee______tttt _nnnn_))))_;;;;
  21.  
  22.      _iiii_nnnn_tttt _ssss_tttt_rrrr_cccc_mmmm_pppp _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  23.  
  24.      _iiii_nnnn_tttt _ssss_tttt_rrrr_nnnn_cccc_mmmm_pppp _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_,,,, _ssss_iiii_zzzz_eeee______tttt _nnnn_))))_;;;;
  25.  
  26.      _iiii_nnnn_tttt _ssss_tttt_rrrr_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  27.  
  28.      _iiii_nnnn_tttt _ssss_tttt_rrrr_nnnn_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_,,,, _ssss_iiii_zzzz_eeee______tttt _nnnn_))))_;;;;
  29.  
  30.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_cccc_pppp_yyyy _((((_cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  31.  
  32.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_nnnn_cccc_pppp_yyyy _((((_cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_,,,, _ssss_iiii_zzzz_eeee______tttt _nnnn_))))_;;;;
  33.  
  34.      _ssss_iiii_zzzz_eeee______tttt _ssss_tttt_rrrr_llll_eeee_nnnn _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_))))_;;;;
  35.  
  36.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_cccc_hhhh_rrrr _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_,,,, _iiii_nnnn_tttt _cccc_))))_;;;;
  37.  
  38.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_rrrr_cccc_hhhh_rrrr _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_,,,, _iiii_nnnn_tttt _cccc_))))_;;;;
  39.  
  40.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_pppp_bbbb_rrrr_kkkk _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  41.  
  42.      _ssss_iiii_zzzz_eeee______tttt _ssss_tttt_rrrr_ssss_pppp_nnnn _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  43.  
  44.      _ssss_iiii_zzzz_eeee______tttt _ssss_tttt_rrrr_cccc_ssss_pppp_nnnn _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  45.  
  46.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_tttt_oooo_kkkk _((((_cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  47.  
  48.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr _((((_cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_,,,, _cccc_hhhh_aaaa_rrrr _****_****_llll_aaaa_ssss_tttt_ssss_))))_;;;;
  49.  
  50.      _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_ssss_tttt_rrrr _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_1111_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_2222_))))_;;;;
  51.  
  52.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_...._hhhh_>>>>
  53.  
  54.      _cccc_hhhh_aaaa_rrrr _****_iiii_nnnn_dddd_eeee_xxxx _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_,,,, _iiii_nnnn_tttt _cccc_))))_;;;;
  55.  
  56.      _cccc_hhhh_aaaa_rrrr _****_rrrr_iiii_nnnn_dddd_eeee_xxxx _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ssss_,,,, _iiii_nnnn_tttt _cccc_))))_;;;;
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ssssttttrrrriiiinnnngggg((((3333CCCC))))                                                          ssssttttrrrriiiinnnngggg((((3333CCCC))))
  71.  
  72.  
  73.  
  74. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  75.      The arguments _s, _s_1, and _s_2 point to strings (arrays of characters
  76.      terminated by a null character).  The functions _ssss_tttt_rrrr_cccc_aaaa_tttt, _ssss_tttt_rrrr_nnnn_cccc_aaaa_tttt, _ssss_tttt_rrrr_cccc_pppp_yyyy,
  77.      _ssss_tttt_rrrr_nnnn_cccc_pppp_yyyy, _ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr, and _ssss_tttt_rrrr_tttt_oooo_kkkk, all alter _s_1.  These functions do not
  78.      check for overflow of the array pointed to by _s_1, or for overlap between
  79.      _s_1 and _s_2.  If overflow of _s_1 occurs, or copying takes place when _s_1 and
  80.      _s_2 overlap, the behavior is undefined.
  81.  
  82.      _ssss_tttt_rrrr_cccc_aaaa_tttt appends a copy of string _s_2, including the terminating null
  83.      character, to the end of string _s_1.  _ssss_tttt_rrrr_nnnn_cccc_aaaa_tttt appends at most _n
  84.      characters.  Each returns a pointer to the null-terminated result.  The
  85.      initial character of _s_2 overrides the null character at the end of _s_1.
  86.  
  87.      _ssss_tttt_rrrr_cccc_mmmm_pppp compares its arguments and returns an integer less than, equal to,
  88.      or greater than 0, based upon whether _s_1 is lexicographically less than,
  89.      equal to, or greater than _s_2.  _ssss_tttt_rrrr_nnnn_cccc_mmmm_pppp makes the same comparison but
  90.      looks at at most _n characters.  Characters following a null character are
  91.      not compared.  _ssss_tttt_rrrr_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp and _ssss_tttt_rrrr_nnnn_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp are case-insensitive versions
  92.      of _ssss_tttt_rrrr_cccc_mmmm_pppp and _ssss_tttt_rrrr_nnnn_cccc_mmmm_pppp, respectively.  Case-insensitive comparison is
  93.      implemented by converting upper-case ASCII characters to lower-case
  94.      before comparison.  Thus _ssss_tttt_rrrr_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp and _ssss_tttt_rrrr_nnnn_cccc_aaaa_ssss_eeee_cccc_mmmm_pppp only give meaningful
  95.      results for the "C" locale (7 bit ASCII).
  96.  
  97.      _ssss_tttt_rrrr_cccc_pppp_yyyy copies string _s_2 to _s_1 including the terminating null character,
  98.      stopping after the null character has been copied.  _ssss_tttt_rrrr_nnnn_cccc_pppp_yyyy copies
  99.      exactly _n characters, truncating _s_2 or adding null characters to _s_1 if
  100.      necessary (ie. if the length of _n is greater than the length of _s_2 ).
  101.      The result will not be null-terminated if the length of _s_2 is _n or more.
  102.      Each function returns _s_1.
  103.  
  104.      _ssss_tttt_rrrr_dddd_uuuu_pppp returns a pointer to a new string which is a duplicate of the
  105.      string pointed to by _s_1. The space for the new string is obtained using
  106.      _mmmm_aaaa_llll_llll_oooo_cccc(3C).  If the new string can not be created, a NULL pointer is
  107.      returned.
  108.  
  109.      _ssss_tttt_rrrr_llll_eeee_nnnn returns the number of characters in _s, not including the
  110.      terminating null character.
  111.  
  112.      _ssss_tttt_rrrr_cccc_hhhh_rrrr (or _ssss_tttt_rrrr_rrrr_cccc_hhhh_rrrr) returns a pointer to the first (last) occurrence of _c
  113.      (converted to a _cccc_hhhh_aaaa_rrrr) in string _s, or a NULL pointer if _c does not occur
  114.      in the string.  The null character terminating a string is considered to
  115.      be part of the string.
  116.  
  117.      _iiii_nnnn_dddd_eeee_xxxx (rrrriiiinnnnddddeeeexxxx) are included as duplicates of _ssss_tttt_rrrr_cccc_hhhh_rrrr (ssssttttrrrrrrrrcccchhhhrrrr) for
  118.      compatibility (see Notes).
  119.  
  120.      _ssss_tttt_rrrr_pppp_bbbb_rrrr_kkkk returns a pointer to the first occurrence in string _s_1 of any
  121.      character from string _s_2, or a NULL pointer if no character from _s_2
  122.      exists in _s_1.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ssssttttrrrriiiinnnngggg((((3333CCCC))))                                                          ssssttttrrrriiiinnnngggg((((3333CCCC))))
  137.  
  138.  
  139.  
  140.      _ssss_tttt_rrrr_ssss_pppp_nnnn (or _ssss_tttt_rrrr_cccc_ssss_pppp_nnnn) returns the length of the initial segment of string
  141.      _s_1 which consists entirely of characters from (not from) string _s_2.
  142.  
  143.      _ssss_tttt_rrrr_tttt_oooo_kkkk considers the string _s_1 to consist of a sequence of zero or more
  144.      text tokens separated by spans of one or more characters from the
  145.      separator string _s_2.  The first call (with pointer _s_1 specified) returns
  146.      a pointer to the first character of the first token, and will have
  147.      written a null character into _s_1 immediately following the returned
  148.      token. The function keeps track of its position in the string between
  149.      separate calls, so that subsequent calls (which must be made with the
  150.      first argument a NULL pointer) will work through the string _s_1
  151.      immediately following that token.  In this way subsequent calls will work
  152.      through the string _s_1 until no tokens remain.  The separator string _s_2
  153.      may be different from call to call.  When no token remains in _s_1, a NULL
  154.      pointer is returned.  Note that a string consisting entirely of non-
  155.      separator characters is considered a single token.  For example, if the
  156.      initial call to _ssss_tttt_rrrr_tttt_oooo_kkkk is made with _s_1 pointing to a string consisting
  157.      entirely of non-separator characters, then the return value from _ssss_tttt_rrrr_tttt_oooo_kkkk
  158.      will be the value of _s_1 passed to _ssss_tttt_rrrr_tttt_oooo_kkkk.
  159.  
  160.      _ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr is a reentrant version of _ssss_tttt_rrrr_tttt_oooo_kkkk.  The current location in the
  161.      string is kept track of in _l_a_s_t_s.  On the first call to _ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr, _l_a_s_t_s
  162.      should be a pointer to a NULL pointer. It is kept updated on each
  163.      successive call to _ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr to point into _s_1 directly after the null
  164.      character.  _l_a_s_t_s must not be changed between calls to _ssss_tttt_rrrr_tttt_oooo_kkkk______rrrr.  The
  165.      feature test macro ______SSSS_GGGG_IIII______RRRR_EEEE_EEEE_NNNN_TTTT_RRRR_AAAA_NNNN_TTTT______FFFF_UUUU_NNNN_CCCC_TTTT_IIII_OOOO_NNNN_SSSS should be defined to make
  166.      this function visible.
  167.  
  168.      _ssss_tttt_rrrr_ssss_tttt_rrrr locates the first occurrence in string _s_1 of the sequence of
  169.      characters (excluding the terminating null character) in string _s_2.
  170.      _ssss_tttt_rrrr_ssss_tttt_rrrr returns a pointer to the located string, or a null pointer if the
  171.      string is not found. If _s_2 points to a string with zero length (i.e., the
  172.      string ""), the function returns _s_1.
  173.  
  174. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  175.      _mmmm_aaaa_llll_llll_oooo_cccc(3C), _mmmm_eeee_mmmm_oooo_rrrr_yyyy(3C), _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C), _ssss_tttt_rrrr_cccc_oooo_llll_llll(3C), _ssss_tttt_rrrr_eeee_rrrr_rrrr_oooo_rrrr(3C),
  176.      _ssss_tttt_rrrr_xxxx_ffff_rrrr_mmmm(3C).
  177.  
  178. NNNNOOOOTTTTEEEESSSS
  179.      All of these functions assume the default locale ``C.''  For some
  180.      locales, _ssss_tttt_rrrr_xxxx_ffff_rrrr_mmmm should be applied to the strings before they are passed
  181.      to the functions.
  182.  
  183.      Declarations for _iiii_nnnn_dddd_eeee_xxxx and _rrrr_iiii_nnnn_dddd_eeee_xxxx are specifically omitted from
  184.      _<<<<_ssss_tttt_rrrr_iiii_nnnn_gggg_...._hhhh_>>>> due to possible naming conflicts. Instead, they are declared
  185.      in _<<<<_ssss_tttt_rrrr_iiii_nnnn_gggg_ssss_...._hhhh_>>>>.
  186.  
  187.      The iiiinnnnddddeeeexxxx, rrrriiiinnnnddddeeeexxxx, ssssttttrrrrccccaaaasssseeeeccccmmmmpppp, ssssttttrrrrnnnnccccaaaasssseeeeccccmmmmpppp routines are from the 4.3BSD
  188.      or 4.3BSD-tahoe standard C library.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.